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1AM  SYSTEM  SPECIFICATION 


1.0  INTRODUCTION 


Purpose  of  the  Svittm  Specification 

The  RAM  System  Specification  ia  a  technical  document 
written  for  eoftware  development  peraonnel.  Together  with 
the  RAM  Functional  Description,  it  guidea  the  aoftware 
development  effort  by  identifying  the  functional  require- 
menta  and  by  providing  atructured  logic  diagrama  that  depict 
the  flow,  control,  and  proceaaing  of  information  within  the 
ayatem. 

The  ayatem  apecification  ia  generic  and  ia  intended  to 
guide  and  facilitate  the  preparation  of  the  language-specific 
program  documentation  and  coding  that  are  necessary  to 
implement  and  operate  RAM  at  an  installation.  y— — 

1.2  References 

1.2.1  IBM,  HIPO — A  Design  Aid  and  Documentation  Tech¬ 
nique.  Technical  Publication  GC20-1851-0. 

White  Plains,  New  Yorki  IBM,  October  1974. 

1.2.2  Amey,  Dorothy  M.i  Feuerverger,  Phillip  H. t 
Guliek,  Roy  M.  Documentation  of  Decision-Aiding 
Software t  RAM  Functional  Description.  McLean, 
Virginia *  Decisions  and  Designs,  Inc.,  September 
1979. 

1.2.3  Amey,  Dorothy  M. i  Feuerwerger,  Phillip  B.i 
Ottllck,  Roy  M.  Documentation  of  Decision-Aiding 
Software t  ram  Users  Manual.  McLean,  Virginia: 
Decisions  and  Designs,  Inc.,  September  1979. 
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1.3.1  HAH  -  RAM  it  an  abbreviation  for  Reaource  Allo¬ 
cation  Model,  reflecting  the  system's  major  area  of  appli¬ 
cability. 

1.3.2  HIPO  -  The  specification  uses  the  standard  Hier¬ 
archy  plus  Znput-Process-Output  (HIPO)  diagramming  technique 
to  depict  the  structural  design  and  logical  flow  of  the 
system.  A  legend  explaining  the  HXPO  diagramming  symbols  is 
included.  Reference  1.2.1  provides  a  complete  description 
of  the  HIPO  documentation  technique. 


2.0  DESIGN  DETAILS 


2.1  Background 

i  Systems  development  personnel  should  refer  to  the  RAM 

Functional  Description#  reference  1.2.2,  in  conjunction  with 
the  documentation  contained  in  this  specification.  The 
functional  description  details  the  resource  allocation  model 
•  implemented  by  RAM  and  discusses  the  specific  functions  that 

the  software  performs.  In  addition,  systems  development 
personnel  may  wish  to  refer  to  the  RAM  User's  Manual, 
reference  1.2.3. 

2.2  General  Operating  Procedures 

RAM  is  a  menu-driven  system.  That  is,  the  system  is 
designed  to  interact  with  the  user  by  presenting  a  sequen¬ 
tial  hierarchy  of  menus  and  asking  the  user  to  respond  by 
selecting  one  option  from  the  current  menu.  If  the  user 
does  not  select  one  of  the  menu  options,  the  system  displays 
the  previous  menu.  In  this  manner,  the  user  moves  up  and 
down  the  hierarchy,  as  desired.  Whenever  data  entry  is 
required  as  a  result  of  option  selection,  the  system  spe¬ 
cifically  requests  the  data  and  specifies  the  format. 

The  system  is  also  designed  to  be  generally  forgiving 
of  procedural  errors  by  the  user. 

2.3  •vstem  Logical  Flow 

RAM  is  a  hierarchically  structured,  modular  system. 

The  system  structure  and  logical  flow  lends  itself  to  pre¬ 
sentation  in  the  form  of  BIFO  diagrams,  whloh  are  contained 
in  this  document. 
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The  main  purpose  of  the  HIPO  diagrams  is  to  provide,  in 
a  pictorial  manner,  the  complete  set  of  modular  elements 
necessary  to  the  operation  of  RAM  including  all  input, 
output,  and  internal  functional  processing.  This  is  done  by 
displaying  input  items  to  the  process  step  which  uses  them, 
defining  the  process,  and  showing  the  resulting  output  of 
the  process  step. 

The  documentation  diagrams  are  designed  and  drawn  in  a 
hierarchical  fashion  from  the  main  calling  routines  to  the 
detail-level  operation/calculation  routines.  Extended 
written  descriptions  are  given  below  a  HIPO  diagram  whenever 
it  is  deemed  necessary. 

A  complete  explanation  of  the  symbolic  notation  used  in 
the  HIPO  diagrams  is  given  in  reference  1.2.1.  An  abbre¬ 
viated  legend  for  the  symbols  used  in  this  specification  is 
given  in  Figure  2-1.  Mote  that: 

a.  External  subroutines  appear  partly  in  the  process 
block  and  partly  out.  Internal  subroutines  are 
shown  within  the  process  block. 

b.  Overview  diagrams  show  general  inputs  and  outputs 
only,  whereas  detail/subroutine-level  diagrams 
show  specific  input/output  tables  and/or  displays. 

c.  Rectangular  boxes  inside  the  input/output  block 
areas  are  generally  used  to  denote  single  data 
items.  Two  or  more  boxes  are  grouped  to  show 
several  data  items  are  input/output. 

d.  Rectangular  boxes  inside  the  process  block  indi¬ 
cate  repetitive  subprocesses. 
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—  —  —  —  —  Data  reference 


Keyed  date  arrows 


Off-page 

connection  arrows 


General  flow  of  data 
among  subprocesses 


Subroutine  invoked 
(Return  is  made  to 
celling  routine) 


Routine  receives  control 

Routine  exits 
or  returns  control 


Information  display  by 
online  indicators  -  prompted 
by  program  execution  or  by 
keyboard  input,  especially  CRT 


r - , 

I  I 

I  I 


Logical  grouping 
of  functions 


Function  identified 
but  not  included  in 
package 


Magnetic  tape 
input/output  medium 


Figur*  2-1 

LBGSND  OF  BXFO  SYMBOLS 


The  HIPO  diagrams  appaar  in  the  next  section,  which 
completes  the  system  specification. 

2.4  HIPO  Documentation 

The  BZPO  diagram  identification  numbers  and  figure 
numbers  used  in  this  section  stand  alone;  i.e. ,  they  start 
with  1.0,  increase  hierarchically,  and  are  independent  of 
the  numbering  scheme  used  to  this  point  in  this  document. 

The  RAM  system  comprises  two  subsystems:  BUILDRAM, 
which  builds  and  exercises  the  resource  allocation  model, 
and  REPRAM,  which  produces  various  reports  based  on  the 
model  and  its  data.  Figure  2-2  is  the  system  structure 
chart.  Figures  2-3  and  2-4  are  the  subsystem  charts  and 
represent  the  overall  program  logic  flows  in  visual  tables 
of  contents.  The  Visual  Table  of  Contents  shows  the  hier¬ 
archical  structure,  the  functional  description  labels,  and 
the  diagram  (chart)  identifiers  of  the  functions  implemented 


by  the  RAM  subsystems. 


BUILDRAM 
SUBSYSTEM 
Figure  2-3 


Figure  2-2 

RAM  SYSTEM  OVERVIEW 


Figure  2-3 

BUILDRAM  SUBSYSTEM  OVERVIEW  AND  VISUAL  TABLE  OF  CONTENTS 


REPRAM 


REPRAM  SUBSYSTEM  OVERVIEW  AND  VISUAL  TABLE  OF  CONTENTS 


Sytttm  Program:  -BUMt.PHAM _  _  Name : 

Diagram  ID:  -2afi - Description — !si*i^5,l/Q — 


3.  A  *v*tam  device  OPEN  command  »  raquired  in  order  to  access  the  RAM  model 
and  data.  The  interface  with  the  system  OPEN  routine  should  be  OPEN's  setting  of 
I/O  flags  in  (or  adjacent  to)  an  I/O  buffer  area  to  denote  the  success  or  failure  of 
access  to  the  device. 

If  an  error  condition  is  detected,  a  non-zero  error  code  is  returned  to  the  caller. 


System /Program :  BUILDRAM  Nan 

Diagram  ID:  3tQ  —  —  Description  -ESiiiillfi 


PROCESS  OUTPUT 


PROCESS  OUTPUT 
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PLNG  t  INST  RESEARCH  RAM 


ITEM 

SPONSOR 

OVERALL 

COST 

C/B 

RANK 

BENEFIT 

BENEFIT 

1 

2) ALUMNI  SURVEY 

25.0 

2.5 

5.0 

2.0 

3 

1 

3) ARCHITECTURAL  SURVEY 

100.0 

10.0 

60.0 

8.0 

17 

1 

4) EXPANSION  PLANNING 

65.0 

6.5 

113.0 

17.4 

21 

1 

1) SECRETARIAL  SERVICES 

10.0 

1.0 

95.0 

95.0 

24 

PLEASE  RETURN  CARRIAGE  TO  CONTINUE 


HIPO  Figure  5.1 

DISPLAY  OF  SPONSOR  RESULTS 


RAM  AND  COST  MATRICES 


RAM  matrix  -  Number  of  Item*  *  k 


Columns  No.  1 : 
No.  2: 
No.  3: 
No.  4: 


Benefit  value  specified  by  the  user 
Over-all  benefit  value 
Total  cost  across  cost  components 
Cost-benefit  ratio 


COST  matrix  -  Number  of  items  3  k 

-  Number  cost  components  *  r 


Columns  No.  1  through  r  »  costs  for  each  of  the  r  components  (usually  r  -  5) 
No.  r  +  1  :  "other"  costs  single  value 


HIPO  Figure  6.2 

STRUCTURE  OF  THE  RAM  AND  COST  MATRICES 


Systtm/Ptogram:  BUILDRAM _ 

Diagram  ID:  &Q - Description 


Systam/Program:  BUILDRAM _  Name:  _ _ 

Diagram  ID:  _ Description  ^nter^ost-Comeonen^Labels _  paqe. 


labels  entered  in  step  1  are  stored  in  the  cost-labels  array.  Also,  the  label 
’  for  other  costs  is  added  to  the  array. 


System/Program:  BUILDRAM _  _  Name:  _ 

Diagram  ID:  _ Description -■  Spon»l 


The  sponsor-item  identifier  numbers  will  be  used  in  the  program  to  determine  index 
locations  in  cost/benefit  matrices  and  for  display  purposes. 


System /Program:  BUILPRAM _  ■  Name:  _ 

Diagram  ID:  — LQ _ Description  Enter  Benefits  and  Costs 


RAM  (cost-benefit)  matrix  and  the  COST  components  matrix  are  created  prior  to 
the  calling  of  this  routine. 

For  the  detail  descriptions  of  sub-processes  2  and  3,  see  diagrams  7.1  and  7.2. 


RAM  matrix  Utap  4.) 


2-3.  For  the  selected  group,  prompt  the  user  for  cost  values  for  each  cost 
component  per  item.  Repeat  for  each  item  within  the  selected  sponsor  group. 

4.  Compute  the  total  cost  over  the  components  for  each  item  and  store  in  the 
RAM  matrix. 


System/Program  BUI  LOR  AM _  _____  Name:  _ 

Diagram  ID:  -15 _ Descr.pt.on  Devel°P  Cross-Sponsor  Weights 
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S.  The  new  value  may  ba  entered  directly  from  keyboard  and  then  converted, 
te*»d  for  validity,  and  stored.  As  an  alternative,  the  "ENTERLINE"  routine 
(diagram  12.3)  may  be  used  to  obtain  the  new  values. 


Extandad  Oascription 
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9.  Sum  the  costs  across  cost-components  for  each  item  and  store  these  values  in 
the  appropriate  column  of  the  RAM  matrix. 


System /Program:  BIHLDRAM _  Name:  _ 

Diagram  ID:  — -  Description — Edit  Cost  Data  . .  Page: 


1 .  Overall  benefit  values  are  computed  by  multiplying  each  sponsor-item  benefit 
values  by  its  fractional  component  in  the  WEIGHTS  vector. 


System/Program ;  BUILDRAM _  Name:  Normalize _ _ _ 

Diagram  ID:  -!2J _ Normalize  Overall  Benefits _  page: 


!  normalized  result  from  step  2  is  typically  multiplied  by  100  to  preserve 
itage  figures  for  output  to  the  calling  routines. 


System /Program:  BUILDRAM _  Name:  MUST  BUY 

Diagram  ID:  _ rw,,P..»n  Process  the  Must  Buy  Option 


2.  Invoke  the  LOCATE  subroutine  (see  diagram  12.51  to  obtain  from  the  user  the 
sponsor-item  identifier  numbers  and  thereby  derive  the  item  index  value  for  the 
requested  item. 


ORDERED  BY 

CUMULATIVE 

CUMULATIVE 

ORDERED  BY 

BENEFIT 

BENEFIT 

COST 

COST 

BENEFIT 

COST-BENEFIT 

CAREER  PLACEMENT 

35 

44.0 

44.0 

35 

CAREER  PLACEMENT 

CTR 

CTR 

73.0 

42 

EXTRACURRICULAR 

125.0 

53 

STUDENT  CENTER 

156.0 
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74 
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61 
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COUNSELING 

77 
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i 

i 


HIPO  Figure  11.1 

COST-BENEFIT  VS.  BENEFIT-ONLY  DISPLAY 


System /Program 


INPUT  PROCESS  OUTPUT 


3.  Any  keyboard  input  or  a  specific  response  may  be  requested  of  the 
user  before  processing  can  continue. 


_  Name:  ENTERLINE 

Enter  Line  Routine _ 


System /Program:  BUILDRAM _  Name:  CHKNUMS 

Diagram  ID  JM _ Check  Numerical  Values 


INPUT  PROCESS  OUTPUT 


ILDRAM _  Name:  EDITLINE 

_ a  Line  of  Numbers 


Extended  Description 

This  routine  differs  from  the  "ENTER LINE”  routine  in  that  it  attempts  to  read 
input  values  from  the  previously  displayed  line  location. 


System /Program  BUILPRAM _ Name:  MENU 

Diagram  ID.  1^.7 _ _  Description  Display  Menu/List  Routine 


2.  The  sort  listing  order  is  a  pre-detined  report  output  sequence  of  item 
identification  numbers  and  has  been  defined  according  to  a  previous  ordering 
(sorting);  for  example,  decreasing  Cost/Benefit  ratio  values  is  one  such  ordering. 
When  the  program  begins,  this  step  sets  the  sort  listing  order  to  depict  increasing 
sponsor-item  identifier  numbers. 


System  Program  REPRAM _  Name _ _ _ 

Diagram  ID  ^.0 -  Description _ Initiate  I/O _ _ _ Page: 


3.  Read  data  commands  are  issued  for  the  required  model  definition  and  data 
variables.  This  is  accomplished  according  to  an  encoded  variable  list  and  in  the 
same  order  as  the  data  items  are  stored. 


PROCESS  OUTPUT 


Description  _  Display  the  Current  Rationale 


SytHm/Ptoyim:  REPRAM _  Name:  _ _ 

Pnywi  ID:  8i3 - Description _ Write  Out  Rationale _ _  Page: 


